The most recent version of this file is available
here.
Release notes for other versions of JAIDA are available
here.
The JMinuit jar file is missing from the distribution. If you are interesting in using JMinuit in your fitting, please refer to forum announcement for instructions.
JAIDA is a Java implementation of AIDA - Abstract Interfaces for Data Analysis. JAIDA 3.2.4 is based on AIDA 3.2. From a user perspective JAIDA 3.2.4 is entirely backwards compatible with AIDA 3.0 and JAIDA 3.0.*.
JAIDA allows Java programmers to quickly and easily create histograms, scatter plots and tuples, perform fits, view plots and store and retrieve analysis objects from files. JAIDA can be used either in a non-graphical environment (for batch processing) or with a simple GUI to display plots. Files written with JAIDA adhere to the AIDA IO standards and can be read by any AIDA compliant analysis system.
Users wishing to get full GUI functionality may be interested in JAS3, a graphical data analysis toolkit built on top of JAIDA. JAS3 can also read .aida files written with JAIDA.
hep.aida.ref.BatchAnalysisFactory to
hep.aida.ref.AnalysisFactory. See Getting
Started for more information.For a full list of changes in JAIDA 3.2.4 see the
JAIDA
change log.
For a full list of changes in AIDA 3.2 see the
AIDA change log.
These release notes list issues specific to the JAIDA implementation of AIDA. In general all of the AIDA documentation applies to JAIDA, in particular the following are useful:
JAIDA is part of the FreeHEP Java Library an "Open Source" library distributed under the terms of the LGPL. If you have questions about the licensing please send a mail to: developers@freehep.org.
This current release of JAIDA is designed to be used with Java 1.4.0 or later. It will not work with earlier versions of Java.
Several JAR files are included in this release. You have to include the ones you need in your CLASSPATH to be able to use JAIDA:
A simple script called aida-setup is provided with JAIDA in the
bin directory, you can run this to set the CLASSPATH appropriately.
Two implementations of the AIDA IAnalysisFactory are provided with JAIDA:
The former includes a simple implementation of the AIDA plotter, the latter contains a dummy implementation of the plotter which allows for AIDA to be run in a batch (or headless) environment. You can explicitly select which analysis factory to use by setting the Java property hep.aida.IAnalysisFactory, e.g.:
java -Dhep.aida.IAnalysisFactory=hep.aida.ref.BatchAnalysisFactory
The built-in plotter is intended mainly as a simple viewer for AIDA plots, for a full-featured GUI implementation based on JAIDA see JAS3.
Histograms - We have provided a full implementation of the AIDA 3.2 histogram interfaces, including histogram arithmetic and projections and slices. For AIDA Histograms and Profiles the statistics (mean and rms) is calculated using ONLY "in-range" data, i.e. data whose bins don't have any components that is either in the UNDERFLOW or in the OVERFLOW bin. In this implementation you can choose to used all the data for the statistics evaluation by adding "useOutflowsInStatistics=true" to the options String when creating Histograms and Profiles. If an AIDA object is filled with a NaN, such value will be ignored in the evaluation of the statistics but it will be considered in the count of the overall number of entries. The number of NaN entries can be obtained by subtracting the number of in-range entries and the number of out-of-range entries from the number of total entries. The number of NaN entries will be displayed in the statistics box when plotting the AIDA object if such number is non zero.
Profile - One and two dimensional Profile histograms are fully implemented.
Clouds - We have provided a full implementation of the AIDA 3.2 cloud interfaces. By default clouds will "auto-convert" to histograms when they reach 100,000 entries. You can turn off auto-conversion by specifying the option "autoConvert=no" when creating the Cloud. A new options controls how clouds are auto-converted to histograms, "margin=0.1" will add a 10% margin to the computed min/max of the cloud which determining the histogram range. The default value is "margin=0.05", "margin=0" will restore the behaviour of the previous release.
DataPointSet - A full implementation of the AIDA 3.2 is implemented including operations among DataPointSets.
Trees and IO - The current implementation of ITree supports reading and writing AIDA standard XML files (.aida files) in either gzip compressed format, or uncompressed format. You can control this via the options parameter when the ITree is created. The default is "compressed=yes". It is also possible to open ROOT files, and if the optional CERNLIB adapter is installed, also PAW files.
Tuples - The whole functionality of AIDA ITuple interface is supported, including support for evaluators, filters and nest ITuples . Full interactive analysis of ITuples is provided by the TupleExplorer plugin in JAS3.
Plotting - Full support for the IPlotter interface is included, including regions and overlays. In the Java implementation the Plotter observes all displayed Histograms and Clouds, and will automatically update the display as necessary. Therefore the IPlotter.refresh() method is currently ignored in the Java implementation. Not all AIDA implementations will do this, so for portability you should still periodically call the refresh() method. Similarly the Java implementation is multi-threaded, so plots will be refreshed while the main program continues to run, and hence the IPlotter.interact() method is also ignored by the Java implementation. Currently it is not possible to plot 3D (or higher dimensionality) data objects. Histograms with variable bin-widths are not yet displayed correctly. Initial support for plot styles has been added in this release.
The following parameters have been added in the Java implementation to the plotter region to access the limits of the plot area: xAxisLowerLimit, xAxisUpperLimit, yAxisLowerLimit, yAxisUpperLimit. To access the region's limits just type:
double xLowerLimit = Double.parseDouble( plotterRegion.parameterValue("xAxisLowerLimit") );
The parameter "mode" is used to control how an object is added to a plot. It is passed as an option in the plot(...) method on the IPlotterRegion and it can take two values: "overlay" to overlay the object to the existing ones, "replace" to replace the existing plots with the one corresponding to the provided object. The latter is equivalent to first clearing the region and then plotting the object. The default value is "overlay".
plotterRegion.plot(hist, "mode=overlay"); or plotterRegion.plot(hist, "mode=replace");
It is possible to control the size of the plotter window via the "plotterWidth" and "plotterHeight" parameters on the plotter:
plotter.setParameter("plotterWidth","400");
plotter.setParameter("plotterHeight","600");
the default plotter size is 600x600. After changing the window size it will be necessary to show the plotter for the changes to take effect.
Ranges - AIDA ranges for plotting can be specified via the options as:
As the options is passed as a string remember to escape the quotes: "range = \"(-1,2)\"".
writeToFile method: there might be some problems when invoking the writeToFile method due to the way the Plotter is currently implemented. In particular the following applies to the situation in which the plotter is showing in the GUI (show() has been invoked) and the data is changed (for example an histogram is filled); this results in a plot updating on the screen to reflect the changes in the data. To do this the data source fires events to the plot to notify that it changed, and, as a result of this the plot updates. To prevent too many events being fired and scripts being slow waiting for the GUI to update we have a 1 second delay after such an event is received before we perform the update (in this time window no more events are fired). Due to this delay it is necessary to synchronize the process of writing the plot to file with the plot updates. To do so, when the writeToFile method is invoked, we submit a process to the Swing thread that will write the plot to file with a delay of a second. One extra complication is that, due to the fact that update events generate other update events on the Swing thread, we cannot guarantee the relative order of such processes with the writeToFile one. In other words there might be cases in which the plot written to file is different to the one represented in the GUI WHEN writeToFile is invoked and the plot is showing.
For this reason we suggest NOT to show the plot to screen when writeToFile is to be invoked.
We will fix the above problem in a future version of the plotter.
Trees - JAIDA can read and write XML files (also known as aida files). In addition it can read PAW (if the optional CERNLIB extension is installed) and Root files (either directly or via a root daemon). Here are some examples:
ITree tree = tf.create("myFile.aida","xml");
ITree tree = tf.create("myFile.paw","paw");
ITree tree = tf.create("myFile.root","root");
ITree tree = tf.create("root://sldrh2.slac.stanford.edu","root",true,false,"scheme=anonymous");
When opening root files the following options are supported:
| Option | Values |
|---|---|
| showAllCycles | By default only the highest numbered cycle is read. If this option is specified then all cylces are shown. |
| scheme | *rood only The authorization scheme to use. Supported values, Anonymous, UsrPwd |
| user | *rood only The user name to use (for UsrPwd scheme) |
| password | *rood only The password to use (for UsrPwd scheme) |
Styles - The AIDA style interfaces are fully implemented. To understand the way styles work it is important to understand the hierarchical structure of the AIDA styles. For each plot a cascade of styles is taken into account: the style associated to the IPlotter, the one associated to the IPlotterRegion, the default one for a given type of data, and the user provided ones when the actual plotting is done (passed via the plot(..) method on the IPlotterRegion). When retrieving the value of a give style parameter we first start from the user provided styles (if any) and navigate down through all the above styles until we find a style for which the given style parameter has been set. This means that the style parameters set in a user provided style will always overwrite the corresponding style parameter set on the IPlotterRegion. Alternatively changing a style parameter on the IPlotterRegion will not affect a plot if a user provided style has been used to render the plot and the given style parameter has been set by the user.
In the Java implementation all the plots listen for changes to all the styles, except for the user provided ones, i.e. the ones that are passed to the IPlotterRegion via its plot(...) method. The plots will update automatically to display any style changes. There is a small caveat here due to a limitation in the AIDA interfaces. In order to modify the plot style of a given object that has been rendered with a user defined style after it has been plotted, it is necessary to first remove the object from the plot (remove(..) method on IPlotterRegion), adding it back again providing the modified style object. We plan to fix this problem for the next release of AIDA: 4.0.
In our Java implementation we have added the following parameters to our implementation of the AIDA styles to allow a finer control over the objects that appear on a given plot. In the table below we list both the standard AIDA parameters the additional parameter names added in our implementation. For each parameter we provide the name, the AIDA object on which they should be set, a description of what they control and the allowed values; for the standard AIDA parameters we also provide the method name that corresponds to such parameters. Please note that all the parameter names and their values are case sensitive. For more information on the AIDA styles please refer to the AIDA API.
| AIDA Interface | Parameter name | Method | Description | Allowed values |
|---|---|---|---|---|
| IBrushStyle | color | setColor, color | Set the color of the brush stroke | Colors rotate |
| opacity | setOpacity, opacity | Set the opacity of the brush stroke | -1, not set | |
| ILineStyle | type | setLineType, lineType | Set the line's type | Not supported |
| thickness | setLineThickness, lineThickness | Set the line's thickness | Not supported | |
| ITextStyle | font | setFont, font | The text's font. | Default "SanSerif" |
| fontSize | setFontSize, fontSize | The text's size. | A number, default is 12 | |
| bold | setBold, isBold | Make the text bold. | true, false | |
| italic | setItalic, isItalic | Make the text italic. | true, false | |
| underlined | setUnerlined, isUnderlined | Make the text underlined. | true, false | |
| IPlotterStyle | showStatisticsBox | Display the statistics box for all the data | true, false | |
| statisticsBoxFont | The font type used in the statistics box | SanSerif, Times, Comics, etc | ||
| statisticsBoxFontStyle | The font style used in the statistics box | plain or 0, bold or 1, italic or 2, boldItalic or 3 | ||
| statisticsBoxFontSize | The font size used in the statistics box | a positive integer | ||
| showLegend | Display the legend on the plot | true, false | ||
| legendFont | The font type used in the legend | SanSerif, Times, Comics, etc | ||
| legendFontStyle | The font style used in the legend | plain or 0, bold or 1, italic or 2, boldItalic or 3 | ||
| legendFontSize | The font size used in the legend | a positive integer | ||
| backgroundColor | The plot's background color | a color, see below | ||
| foregroundColor | The plot's foreground color | a color, see below | ||
| dataAreaColor | The data area's background color | a color, see below | ||
| dataAreaBorderType | The data area's border type | bevelIn or 0, bevelOut or 1, etched or 2, line or 3, shadow or 4 | ||
| hist2DStyle | The way a histogram2D is represented | box or 0, ellipse or 1, colorMap or 2 | ||
| showAsScatterPlot | For scatter plots only to switch between binned and unbinned representation | true, false. The default is true. | ||
| showTitle | Display the title. | true, false. The default is true. | ||
| IDataStyle | showHistogramBars | Display the line around the histogram's bars | true, false | |
| fillHistogramBars | Fill the histogram's bars | true, false | ||
| showErrorBars | Show the error bars | true, false | ||
| errorBarsColor | The error bars color | a color, see below | ||
| profileErrors | The type of error bars for profile plots | spread or 0, errorOnMean or 1. The default is spread. | ||
| showDataPoints | Show data points on top of the histogram's bars | true, false | ||
| connectDataPoints | Connects the data points with a line | true, false | ||
| lineBetweenPointsColor | The color of the line between the points | a color, see below | ||
| functionLineColor | The color of a function | a color, see below | ||
| showStatisticsBox | Display the statistics box for a given data set | true, false | ||
| IAxisStyle | label | The axis label | a string | |
| scale | The scale of the axis | lin, linear, log, logarithmic | ||
| type | The axis type | double, int, string, date | ||
| allowZeroSuppression | To allow zero suppression | true, false. The default is false. | ||
| IFillStyle | pattern | setPattern, pattern | Set the pattern of the filling | Not supported |
| colorMapScheme | The type of color map for 2D histograms | warm or 0, cool or 1, thermal or 2, rainbow or 3, grayscale or 4 | ||
| IMarkerStyle | shape | setShape, shape | The marker's shape | See below |
| size | The size of the marker | a positive integer | ||
The colors can be passed to the styles in the following formats:
The marker's shape can be either a string or a number (a String number); the available shapes are: "dot" or "0", "box" or "1", "triangle" or "2", "diamond" or "3", "star" or "4", "verticalLine" or "5", "horizontalLine" or "6", "cross" or "7", "circle" or "8" and "square" or "9".
Fitting - The flexible design of the IFitter interface allows the user to switch very easily the optimizer engine used in the minimization process and the type of fit method used. We currently support three optimizers: Minuit and Uncmin and JMinuit. They can be accessed by specifying the fminuit, uncmin and jminuit for the engine when creating the fitter. Up to this release minuit has been used to specify Minuit; we still support this but from the next release this will be used for JMinuit instead.
The available fit methods are:
The following link provides the fit methods definition.
Functions- Two types of functions can be created with the IFunctionFactory: built-in functions and scripted functions. Currently the only built-in functions we provide are the Polynomial, the Exponential, the one and two dimensional Gaussian that can be created through the createFunctionByName method of the IFunctionFactory using for the functions model p0, p1, ... , e, g and g2 respectively. No operations among them are currently supported.
The following table shows the name and the list of parameters for each of the built-in functions:
| Polynomial of order n | pn | p0, p1,....,p(n-1) |
| Exponential | e | amplitude, exponent |
| Gaussian 1-dimensional | g | amplitude, mean, sigma |
| Gaussian 2-dimensional | g2 | amplitude, meanX, sigmaX, meanY, sigmaY |
It is possible to create functions by name by adding any of the built in functions, e.g. "g0 + p1".
For more complicated functions the user should create scripted functions though the createFunctionFromScript method.
The following list details which parts of the AIDA standard are not fully implemented:
JAIDA is written entirely in Java, and therefore works on any platform with support for Java. JAIDA also contains code for reading PAW files and for using the Minuit fitter. Both of these components use native code from CERNLIB, and to use them you will need to download and install the additional CERNLIB_Adapter for your platform in order to use these features.
For discussion of features or problems related to JAIDA please use the JAIDA discussion forum. To report bugs or request enhancements you can also use the JAIDA bug database.
If you are using the hep.aida.ref.AnalysisFactory you can export your plots to a graphics file through the writeToFile(String fileName, String type) method on the IPlotter. In order to do this you need to download the following jar files from the FreeHEP repository and add them to your CLASSPATH:
The following example illustrates how to embed one (or more) JAIDA plotters into your own Java application. The example makes use of the hep.aida.ref.plotter.PlotterUtilities class which contains several methods for assisting in interfacing JAIDA to other Java applications.
import hep.aida.*;
import hep.aida.ref.plotter.PlotterUtilities;
import java.awt.BorderLayout;
import java.awt.event.ActionEvent;
import java.util.Random;
import javax.swing.*;
/**
* An example of how to embed a JAIDA IPlotter into your own application.
*/
public class AIDAEmbed extends JPanel
{
/** Creates a new instance of AIDAEmbed */
public AIDAEmbed()
{
super(new BorderLayout());
IAnalysisFactory af = IAnalysisFactory.create();
ITree tree = af.createTreeFactory().create();
IHistogramFactory hf = af.createHistogramFactory(tree);
IHistogram1D h1d = hf.createHistogram1D("Test", 50, -3, 3);
// Fill with junk
Random rand = new Random();
for (int i = 0; i < 10000; i++)
h1d.fill(rand.nextGaussian());
// Create an IPlotter
IPlotter plotter = af.createPlotterFactory().create();
plotter.currentRegion().plot(h1d);
// Now embed the plotter
add(PlotterUtilities.componentForPlotter(plotter), BorderLayout.CENTER);
}
/**
* @param args the command line arguments
*/
public static void main(String[] args)
{
JFrame frame = new JFrame("Embedded AIDA");
JMenuBar bar = new JMenuBar();
JMenu menu = new JMenu("File");
JMenuItem item = new JMenuItem(new ExitAction());
menu.add(item);
bar.add(menu);
frame.setJMenuBar(bar);
frame.setContentPane(new AIDAEmbed());
frame.setDefaultCloseOperation(frame.EXIT_ON_CLOSE);
frame.pack();
frame.show();
}
private static class ExitAction extends AbstractAction
{
ExitAction() { super("Exit"); }
public void actionPerformed(ActionEvent e) { System.exit(0); }
}
}
The following example illustrates how to use JAIDA in a servlet to send graphics back to a user's web browser.
import hep.aida.*;
import hep.aida.ref.plotter.PlotterUtilities;
import java.io.IOException;
import java.util.Random;
import javax.servlet.ServletConfig;
import javax.servlet.ServletException;
import javax.servlet.ServletOutputStream;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
public class AIDAServlet extends HttpServlet
{
private IPlotter plotter;
/** Initializes the servlet.
*/
public void init(ServletConfig config) throws ServletException
{
super.init(config);
IAnalysisFactory af = IAnalysisFactory.create();
ITree tree = af.createTreeFactory().create();
IHistogramFactory hf = af.createHistogramFactory(tree);
IHistogram1D h1 = hf.createHistogram1D("Test", 50, -4, 4);
Random r = new Random();
for (int i = 0; i < 10000; i++)
h1.fill(r.nextGaussian());
plotter = af.createPlotterFactory().create("Test");
plotter.region(0).plot(h1);
}
public void doGet(HttpServletRequest req, HttpServletResponse res) throws ServletException, IOException
{
ServletOutputStream out = res.getOutputStream();
res.setContentType("image/png");
PlotterUtilities.writeToFile(plotter,out,"png",null);
out.close();
}
}
JAIDA is intended for use in simple standalone Java applications. It provides the full AIDA functionality for Java, but only limited "GUI" functionality. JAS3 builds on the functionality of JAIDA and adds many GUI based interactive analysis tools. JAS3 is available from http://jas.freehep.org/jas3.
Python is a popular object-oriented scripting language. Jython is an implementation of Python written in Java. Jython is able to access any Java object as if it were a Python object. Thus it is very easy to use JAIDA with Jython. The combination provides a very convenient way of exploring the capabilities of JAIDA.
To use it follow steps below:
Run the script below just by typing:
jython UsingJAIDAFromJython.py
where UsingJAIDAFromJython.py contains:
from hep.aida import *
from java.lang import *
from java.util import *
System.getProperties().setProperty("hep.aida.IAnalysisFactory","hep.aida.ref.AnalysisFactory")
true = Boolean("true");
false = Boolean("false");
factory = IAnalysisFactory.create();
tree = factory.createTreeFactory().create("UsingJAIDAFromJython.aida","xml",false,true);
hf = factory.createHistogramFactory(tree);
#fitter = factory.createFitFactory().createFitter("Chi2","uncmin");
tree.mkdir("/Histograms");
tree.cd("/Histograms");
h1 = hf.createHistogram1D("Histogram 1D",50,-3,3);
h2 = hf.createHistogram2D("Histogram 2D",40,-3,3,40,-3,3);
tree.mkdir("/Clouds");
tree.cd("/Clouds");
c1 = hf.createCloud1D("Cloud 1D");
c2 = hf.createCloud2D("Cloud 2D");
page1 = factory.createPlotterFactory().create("Page1");
page1.show();
page1.createRegions(2,2);
page1.region(0).plot(h1);
page1.region(1).plot(h2);
page1.region(2).plot(c1);
page1.region(3).plot(c2);
r = Random()
def fill():
for i in range(10000):
h1.fill(r.nextGaussian())
h2.fill(r.nextGaussian(),r.nextGaussian())
c1.fill(r.nextGaussian())
c2.fill(r.nextGaussian(),r.nextGaussian())
fill()
tree.commit();
Pnuts is a nice java scripting language and it can downloaded it from https://pnuts.dev.java.net/.
The above AIDA script in Pnuts looks like:
IAnalysisFactory = class hep.aida.IAnalysisFactory
factory = IAnalysisFactory::create()
tree = factory.createTreeFactory().create("UsingJAIDAFromPnuts.aida","xml",false,true);
hf = factory.createHistogramFactory(tree);
tree.mkdir("/Histograms");
tree.cd("/Histograms");
h1 = hf.createHistogram1D("Histogram 1D",50,-3,3);
h2 = hf.createHistogram2D("Histogram 2D",40,-3,3,40,-3,3);
tree.mkdir("/Clouds");
tree.cd("/Clouds");
c1 = hf.createCloud1D("Cloud 1D");
c2 = hf.createCloud2D("Cloud 2D");
page1 = factory.createPlotterFactory().create("Page1");
page1.show();
page1.createRegions(2,2);
page1.region(0).plot(h1);
page1.region(1).plot(h2);
page1.region(2).plot(c1);
page1.region(3).plot(c2);
Random = class java.util.Random
r = Random()
for( i = 0; i < 10000; i++ ) {
h1.fill(r.nextGaussian())
h2.fill(r.nextGaussian(),r.nextGaussian())
c1.fill(r.nextGaussian())
c2.fill(r.nextGaussian(),r.nextGaussian())
}
tree.commit();
To execute the above script follow the steps below:
where "pnuts" is the executable that comes with the Pnuts distribution appropriate for your platform.
To access the Java implementation of the AIDA interfaces from C++ you need to download the AIDAJNI glue code that will allow you to operate on the JAIDA objects from C++.
Example C++ code follows:
£include <iostream>
£include <cstdlib>
£include "AIDA/AIDA.h"
£include "JIAnalysisFactory.h"
using namespace AIDA;
int main(int argc, char *argv[]) {
AIDA::IAnalysisFactory* factory = AIDA_createAnalysisFactory();
ITree* tree = factory->createTreeFactory()->create("UsingJAIDAFromCPP.aida","xml",false,true);
IHistogramFactory* hf = factory->createHistogramFactory(*tree);
tree->mkdir("/Histograms");
tree->cd("/Histograms");
IHistogram1D* h1 = hf->createHistogram1D("Histogram 1D",50,0,10);
IHistogram2D* h2 = hf->createHistogram2D("Histogram 2D",40,0,10,40,0,10);
tree->mkdir("/Clouds");
tree->cd("/Clouds");
ICloud1D* c1 = hf->createCloud1D("Cloud 1D");
ICloud2D* c2 = hf->createCloud2D("Cloud 2D");
IPlotter* page1 = factory->createPlotterFactory()->create("Page1");
page1->show();
page1->createRegions(2,2);
page1->region(0)->plot(*h1);
page1->region(1)->plot(*h2);
page1->region(2)->plot(*c1);
page1->region(3)->plot(*c2);
srand( 0 );
for ( int i = 0; i < 10000; i++ ) {
h1->fill( 10*rand()/(double)RAND_MAX );
h2->fill( 10*rand()/(double)RAND_MAX, 10*rand()/(double)RAND_MAX);
c1->fill( 10*rand()/(double)RAND_MAX );
c2->fill( 10*rand()/(double)RAND_MAX, 10*rand()/(double)RAND_MAX);
}
tree->commit();
delete factory;
return 1;
}
Please follow the link on how to use JAIDA from Geant4.